Repository navigation
Claude Code: start a stopped transcript tailer again, park an idle one - #818
Merged
Merged
Conversation
In dev mode nothing watched the transcript tailer: once it was killed, or failed before it could report, no hook started another, and every later call of the run read as reconcile.fabricated. It also gave up after two hours with no new line, or with no transcript yet, while the run was open. - The hook hands each run's tailer a lock it holds for its life. Each hook event of the run checks it; when it is free, the hook records a signed tailer_lost and starts a new tailer where the stopped one got (at most 10 times a run). - The tailer appends [transcript, offset, digest] to a progress log after each line it reports, after the hook's first line of start offsets. A new tailer reads on from there, so no line is read twice or skipped, and it checks the bytes already read against the digests: an edit made while no tailer ran is still a tailer_lost. - A dev-mode tailer quiet for IDLE_TAILER_S parks with no gap, and the run's next event starts it again. System mode keeps its idle limit. Refs #815 Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
1 task done
Review fixes for the stopped-tailer restart: - A tailer started at SessionEnd (the first event after it parked or was killed) had its first wake as its last, and listed the sub-agents' transcripts only once the main one was open: it read the main one alone. It now opens the main one before listing them. - The hook starts no tailer for a lock file in system mode, where the runtime dir is the agent's, and none for a run it found ended. - SessionEnd's cleanup takes a file the tailer removed meanwhile. - Tests: restarts counted through hook events up to the cap, and a lock removed between the hook's open and its lock. - docs/limits.md: the agent's user can also write the progress log, and a missing log reads on from where the hook last saw the transcripts. Signed-off-by: LoopGlitch26 <53336715+LoopGlitch26@users.noreply.github.com>
LoopGlitch26
enabled auto-merge (squash)
November 13, 2026 13:31
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Most of the false
reconcile.fabricatedgaps from Claude Code come from the transcript tailer stopping while the run goes on. Calls made after that have a decide but no tool use in the record. The field report in #815 (7 days, 25,746 calls, 3,703 fabricated, 121 tailer_lost, Tracekit 1.5.3, desktop app, parallel sessions, Task sub-agents) matches what we measured on our own store on 11-08.What was wrong (origin/main)
tracekit/integrations/claude_code.py:443returns as soon as the session state says the run has a tailer. In dev mode nothing watches it either: the agent's token isn't grantedtailer_heartbeat(tracekit/signer/service.py:445), sotracekit/tailer.py:285stops sending heartbeats. A tailer that was killed, or failed before it could report, left no gap (docs/limits.md:93), and every later call of the run read as fabricated.IDLE_TAILER_S(2 h,tracekit/tailer.py:65) with no new line, or with no transcript yet, it senttailer_lostand exited (tracekit/tailer.py:321,:323). A run stays open while an approval waits, and a session can sit quiet before its first prompt. Every call after that was fabricated._subagents(tracekit/tailer.py:211-218) and_seen(claude_code.py:426-434) match the real layout. I checked this on a machine with Claude Code 2.1.x transcripts, file names and structure only: 1,458<session>/subagents/agent-*.jsonl, 223<session>/subagents/workflows/wf_*/agent-*.jsonl, and 42journal.jsonlfiles there that aren't transcripts. Nothing is nested deeper, and workflow agents' lines carry the parent session's id. The glob has been right since 1.5.1 (1.5.1: gap noise from Claude Code runs, DESK's NEEDS YOU and SPAN #471). On 1.5.x, workflow calls go unread when the tailer stops (cause 1 or 2), and workflows run long and in parallel, so they lose many calls. The restart test covers a sub-agent and a workflow transcript.What this changes
tailer_lost("stopped without a word … a new one reads on from where it stopped (restart n of at most 10)") and starts a new tailer. The kernel releases the lock when the process dies, so a SIGKILL is caught too. After 10 restarts in a run the gap says the tailer won't be started again (lean:RESTARTS).[transcript, offset, sha256 of the bytes before]. A new tailer starts from those offsets, so nothing is read twice or skipped. A transcript the old tailer never reported from is read from its start. Before reading on, the new tailer checks the bytes already read against the digest, so a line edited while no tailer ran is still a signedtailer_lost. A tailer that ends for good (the run ended, SessionEnd, or a loss it reported) removes its lock and log, so no hook restarts it.IDLE_TAILER_Swith no new line, or with no transcript yet, a dev-mode tailer writes"parked"and exits with no gap. The run's next hook event starts it again from its offsets. A transcript that never appears by SessionEnd is still atailer_lost.docs/limits.md(the dev-mode row) anddocs/coding-agents.md(the gap list).Before and after
A scripted Claude Code-shaped run against a real dev signer process in a temp HOME. Hooks go through
claude_code.handlewith Claude Code's payloads, and each tailer runs in a thread of the script on the handle the hook wrote. There are three parallel sessions:A has a main transcript, a Task sub-agent and a workflow agent, and its tailer is killed mid-run.
B goes quiet past the idle limit (scaled to 3 s), then continues.
C gets its first prompt only after the idle limit.
D's tailer is killed and SessionEnd is the next event. Meanwhile its sub-agent and workflow agent make 5 calls no hook decided. This runs against the signer's real 5 s grace window.
The run also has true gaps planted on purpose: in A, a tool use no hook decided and a decide that no transcript asks for, plus D's 5 calls. 91 hook-decided calls in total. Counts are from
tracekit report --json.reconcile.fabricatedreconcile.hook_missingtailer_lostHow it was tested
tests/test_tailer.py. Each one failed on origin/main.tailer_lost.hook_missing._prune).tests/test_tailer.py,test_reconcile.py,test_hook_v2.py,test_hook_invocation.py,test_contract_claude_code.py,test_harness_hooks_v2.py,test_agent_hooks.py,test_signer_completeness.pyandtest_docs.py: 547 passed. E11 (L1 tampering) gives the same result as before.make test-ts lint build test):test_audit.py::test_the_guard_line_names_the_calls_files_agent(gptme), which fails the same way on origin/main 5dd9eba without this change.python -Iimports the main checkout through the editable install, so the restart test runs the tailer in process and the lock test uses a real child process. CI, on one checkout, runs the hook tests with real tailer processes.Not in this PR
hook_missingfor tools Claude Code runs without a PreToolUse (our 11-08 list: Agent, Artifact, ToolSearch, WebFetch, Skill, TaskStop, SendUserFile). That list needs checking against Claude Code 2.1.x before reconcile labels any call "unhooked". Field report: Claude Code, 7 days on macOS #815 has 42 of these.hook_missingandfabricatedpairs when a call is decided in one run of a session and read in another. Fixing that means reconciling across a session's runs in the signer.Refs #815